home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -in_the_mag- / workbench / adf / adflib / adflib.lha / Docs / API.txt < prev   
Text File  |  1999-01-10  |  7KB  |  269 lines
  1. The ADFlib API quick overview
  2. *****************************
  3.  
  4.  
  5. Always read ADFlib structures, never change a value directly, the
  6. behaviour of the library could then become unforeseeable.
  7.  
  8.  
  9.  
  10. Minimal C program with ADFlib
  11. -----------------------------
  12.  
  13. #include<stdio.h>  /* for puts() */
  14.  
  15. #include"adflib.h"
  16.  
  17. ENV_DECLARATION;
  18.  
  19. int main(int argc, char *argv[])
  20. {
  21.     adfEnvInitDefault();
  22.  
  23.     puts("hello world");
  24.  
  25.     adfEnvCleanUp();
  26. }
  27.  
  28.  
  29.  
  30.  
  31. Device
  32. ------
  33.  
  34. struct Device {
  35.     int devType;               /* see adf_str.h */
  36.     BOOL readOnly;
  37.     long size;                 /* in bytes */
  38.  
  39.     int nVol;                  /* partitions */
  40.     struct Volume** volList;  
  41.  
  42.     long cylinders;            /* geometry */
  43.     long heads;
  44.     long sectors;
  45.  
  46.     BOOL isNativeDev;
  47.     void *nativeDev;
  48. };
  49.  
  50. struct Device* adfMountDev(char* name)
  51.  mounts and allocates a device (real or dump)
  52.  
  53. void adfDeviceInfo(struct Device* dev)
  54.  prints device info to stdout : must be rewritten for another GUI
  55.  
  56. void adfUnMountDev(struct Device* dev)
  57.  
  58. void adfCreateHd(struct Device* dev, int nbPartitions, struct Partition** part)
  59.  create a filesystem for harddisk with one or several partition
  60.  (see hd_test2.c)
  61.  
  62. void adfCreateFlop(struct Device* dev, char* name, int flags)
  63.  flags are for ffs, dircache or international (see fl_test.c)
  64.  
  65.  
  66. Volume
  67. ------
  68.  
  69. struct Volume {
  70.     struct Device* dev;
  71.  
  72.     SECTNUM firstBlock;     /* first block of data area (from beginning of device) */
  73.     SECTNUM lastBlock;      /* last block of data area  (from beginning of device) */
  74.     SECTNUM rootBlock;      /* root block (from firstBlock) */
  75.  
  76.     char dosType;           /* FFS/OFS, DIRCACHE, INTERNATIONAL */
  77.     BOOL bootCode;
  78.     int datablockSize;      /* 488 or 512 */
  79.  
  80.     char *volName;
  81.  
  82.     long bitmapSize;             /* in blocks */
  83.     SECTNUM *bitmapBlocks;       /* bitmap blocks pointers */
  84.     struct bBitmapBlock **bitmapTable;
  85.     BOOL *bitmapBlocksChg;
  86.  
  87.     SECTNUM curDirPtr;
  88. };
  89.  
  90.  
  91. struct Volume* adfMount(struct Device* dev, int partition, BOOL readOnly)
  92.  The first partition is #0
  93.  To be called after adfCreateFlop(), adfCreateHd() or adfMountDev().
  94.  
  95. void adfVolumeInfo(vol)
  96.  Display volume info to stdout, must be rewritten for another GUI
  97.  
  98. void adfUnMount(struct Volume *vol)
  99.  
  100.  
  101. Dump device (.ADF)
  102. ------------------
  103.  
  104. struct adfCreateDumpDevice(char*, int cyl, int heads, int sectors)
  105.  To be used in place of adfMountDev(). Create a filename of the right size,
  106.  nothing else
  107.  
  108.  
  109. File
  110. ----
  111.  
  112. struct File* adfOpenFile(struct Volume *volume, char* filename, char* mode)
  113.  mode = "r" or "w"
  114.  
  115. void adfCloseFile(struct File* file)
  116.  
  117. long adfReadFile(struct File* file, long length, unsigned char* buffer)
  118.  returns the number of bytes read
  119.  
  120. long adfWriteFile(struct File* file, long length, unsigned char* buffer)
  121.  returns the number of bytes written
  122.  
  123. BOOL adfEndOfFile(struct File* file)
  124.  
  125.  
  126. Directory
  127. ---------
  128.  
  129. struct List* adfGetDirEnt(struct Volume* vol, SECTNUM nSect)
  130.  Returns a linked list with the directory entries. Each cell content of the list
  131.  must be freed with adfFreeEntry()
  132.  
  133. void adfFreeEntry(struct Entry *entry)
  134.  
  135. SECTNUM adfChangeDir(struct Volume* vol, char* dirname)
  136.  change current directory
  137.  
  138. void adfParentDir(struct Volume* vol)
  139.  change current directory
  140.  
  141. void printEntry(struct Entry* entry)
  142.  print the cell content to stdout
  143.  
  144. void CreateDir(struct Volume* vol, SECTNUM parentSect, char* name)
  145.  
  146.  
  147.  
  148. Callbacks mechanism
  149. -------------------
  150.  
  151. * The library environment : 'struct Env adfEnv'
  152.  
  153. This variable is the only global variable of the library. It contains
  154. callbacks for error and notification messages, and global variables.
  155. By default, adfEnvInitDefault() initialize adfEnv functions that display
  156. messages to stderr. You must use adfSetEnv() to use your own defined
  157. functions.
  158. The environment must be clean up with adfEnvCleanUp().
  159.  
  160. Four functions are available :
  161. - (*adfEnv.eFct)(char*), called by ADFlib for a fatal error. It STOPS 
  162.   the library : you must redefine yourself a more friendly to handle 
  163.   this kind of error.
  164. - (adfEnv.wFct)(char*), called for warnings. It is called when something wrong
  165.   happens, but processing can continue.
  166. - (adfEnv.vFct)(char*), called to display verbose messages.
  167. - (*adfEnv.notifyEnv)(SECTNUM p, int t), called to tell that 
  168.   the volume structure has changed. The value p give where the change appeared, 
  169.   t the type of the value (ST_DIR,ST_FILE,...).
  170.  
  171. The environment also contains access to nativeFunctions.
  172.  
  173.  
  174. * Native device and functions
  175.  
  176. By default, the library is compiled to manage .ADF files (dump files) and
  177. real devices like harddisk and removable disks (called native devives) 
  178. on ONE defined plateform (WinNT/Intel or Linux/68k...)
  179.  
  180. To add a new plateform to be supported by ADFlib, you must write your
  181. own files adf_nativ.h and adf_nativ.c.
  182.  
  183. . data types
  184.  
  185. adf_nativ.h defines two structures :
  186. - 'struct nativeDev'. It contains all the variable necessary for 
  187.   the native device management. You can add here whatever you what to
  188.   be able to manage your real device on your plateform !
  189. - 'struct nativeFunctions'. It defines the minimal API between ADFlib and
  190.   the specific native part. The functions names and prototypes must not be
  191.   changed, since they are called by the library. It is possible to add
  192.   other functions.
  193.  
  194. The type device 'struct Device' contains one variable 'void* nativeDev'.
  195. It is allocated within adf_nativ.c by adfInitDevice().
  196. Another variable 'BOOL isNativeDev' tells if the ADFlib is working with
  197. a dump file (.ADF) or a real device.
  198.  
  199. 'adfEnv' contains one variable 'void *nativeFct'. adfEnvInitDefault()
  200. allocates it by calling the function adfInitNativeFct().
  201.  
  202.  
  203. . callback functions :
  204.  
  205. The structure 'struct nativeFunctions' must have at least :
  206.   BOOL (*adfInitDevice)(struct Device*, char*)
  207.   BOOL (*adfNativeReadSector)(struct Device*, long, int, unsigned char*)
  208.   BOOL (*adfNativeWriteSector)(struct Device*, long, int, unsigned char*)
  209.   BOOL (*adfIsDevNative)(char*)
  210.   void (*adfReleaseDevice)()
  211.  
  212.  
  213. For example, adfMountDev() calls adfInitDevice() this way :
  214.   struct nativeFunctions *nFct;
  215.   
  216.   ... /* struct Device* dev allocation */
  217.  
  218.   nFct = adfEnv.nativeFct; /* was of type void* */
  219.  
  220.   /* only once ! */
  221.   dev->isNativeDev = (*nFct->adfIsDevNative)(filename);
  222.  
  223.   /* choose between dump or a real device */
  224.   if (dev->isNativeDev)
  225.       (*nFct->adfInitDevice)(dev, filename);
  226.   else
  227.       adfInitDumpDevice(dev, filename);
  228.  
  229.  
  230. You must define one function to initialize a device, for example :
  231.  
  232. BOOL myInitDevice(struct Device *dev, char* name)
  233. {
  234.     /* allocate and initailize dev->nativeDev */
  235.  
  236.     /* return TRUE if everything happens right */
  237. }
  238.  
  239. or
  240.  
  241. BOOL myIsDevNative(char* name)
  242. {
  243.     /* for a Unix like platform */
  244.     return( strncmp("/dev/",name,5)==0 );
  245. }
  246.  
  247.  
  248.  
  249. And so on to read, write a 512 bytes block, and release the native device.
  250.  
  251.  
  252. The function 'adfInitNativeFct()', also defined in adf_nativ.c (and .h),
  253. makes the names and the ADFlib native API :
  254.  
  255. void adfInitNativeFct()
  256. {
  257.     struct nativeFunctions *nFct;
  258.  
  259.     nFct = (struct nativeFunctions*)adfEnv.nativeFct;
  260.  
  261.     nFct->adfInitDevice = myInitDevice ;
  262.     nFct->adfNativeReadSector = myReadSector ;
  263. ...
  264. }
  265.  
  266. But the prototypes must stay the same !
  267.  
  268.  
  269.